---
layout: m1x_rest
title: Customer Addresses
---

JSON responses on this page contributed by Tim Reynolds


<ul class="introduction-menu">
    <li><a href='#RESTAPI-Resource-CustomerAddresses-RESTAPI-CustomerAddresses'>REST API: Customer Addresses</a>
    <ul>
        <li><a href='#RESTAPI-Resource-CustomerAddresses-URI--customers--customerid-addresses'>URI: /customers/:customer_id/addresses</a>
        <ul>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-GET-customers--customerid-addresses'>HTTP Method: GET /customers/:customer_id/addresses</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-POST-customers--customerid-addresses'>HTTP Method: POST /customers/:customer_id/addresses</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-PUT-customers--customerid-addresses'>HTTP Method: PUT /customers/:customer_id/addresses</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-DELETE-customers--customerid-addresses'>HTTP Method: DELETE /customers/:customer_id/addresses</a></li>
        </ul>
        </li>
        <li><a href='#RESTAPI-Resource-CustomerAddresses-URI--customers-addresses--addressid'>URI: /customers/addresses/:address_id</a>
        <ul>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-GET-customers-addresses--addressid'>HTTP Method: GET /customers/addresses/:address_id</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-POST-customers-addresses--addressid'>HTTP Method: POST /customers/addresses/:address_id</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-PUT-customers-addresses--addressid'>HTTP Method: PUT /customers/addresses/:address_id</a></li>
            <li><a href='#RESTAPI-Resource-CustomerAddresses-HTTPMethod-DELETE-customers-addresses--addressid'>HTTP Method: DELETE /customers/addresses/:address_id</a></li>
        </ul>
        </li>
    </ul>
    </li>
    <li><a href='#RESTAPI-Resource-CustomerAddresses-PossibleHTTPStatusCodes'>Possible HTTP Status Codes</a></li>
</ul>


<h3><a name="RESTAPI-Resource-CustomerAddresses-RESTAPI-CustomerAddresses"></a>REST API: Customer Addresses</h3>

<h4><a name="RESTAPI-Resource-CustomerAddresses-URI--customers--customerid-addresses"></a>URI: /customers/:customer_id/addresses</h4>

<p>Allows you to manage existing customer addresses.</p>

<p><b>URL Structure</b>: http://magentohost/api/rest/customers/:customer_id/addresses<br/>
<b>Version</b>: 1</p>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-GET-customers--customerid-addresses"></a>HTTP Method: GET /customers/:customer_id/addresses</h5>

<p><b>Description</b>: Allows you to retrieve the list of existing customer addresses.<br/>
<b>Notes</b>: The list of attributes that will be returned for customer addresses is configured in the Magento Admin Panel. The Customer user type has access only to his/her own addresses. Also, Admin can add additional non-system customer address attributes by selecting <b>Customers</b> &gt; <b>Attributes</b> &gt; <b>Manage Customer Address Attributes</b> (available only in Magento Enterprise Edition). If these attributes are set as visible on frontend, they will be returned in the response.</p>



<p><b>Authentication</b>: Admin, Customer<br/>
<b>Default Format</b>: XML<br/>
<b>Parameters</b>:<br/>
<em>No Parameters</em></p>

<p><b>Example:</b></p>

<div class='panelMacro'><table class='infoMacro'><tr><td>GET http://magentohost/api/rest/customers/1/addresses</td></tr></table></div>

<p><b>Response Body:</b></p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;?xml version="1.0"?&gt;
&lt;magento_api&gt;
  &lt;data_item&gt;
    &lt;entity_id&gt;2&lt;/entity_id&gt;
    &lt;firstname&gt;John&lt;/firstname&gt;
    &lt;lastname&gt;Doe&lt;/lastname&gt;
    &lt;city&gt;PA&lt;/city&gt;
    &lt;region&gt;Palau&lt;/region&gt;
    &lt;postcode&gt;19103&lt;/postcode&gt;
    &lt;country_id&gt;US&lt;/country_id&gt;
    &lt;telephone&gt;610-634-1181&lt;/telephone&gt;
    &lt;prefix&gt;Dr.&lt;/prefix&gt;
    &lt;middlename&gt;&lt;/middlename&gt;
    &lt;suffix&gt;Jr.&lt;/suffix&gt;
    &lt;company&gt;&lt;/company&gt;
    &lt;fax&gt;&lt;/fax&gt;
    &lt;vat_id&gt;123456789&lt;/vat_id&gt;
    &lt;street&gt;
      &lt;data_item&gt;2356 Jody Road Philadelphia&lt;/data_item&gt;
      &lt;data_item&gt;844 Jefferson Street; 4510 Willis Avenue&lt;/data_item&gt;
    &lt;/street&gt;
    &lt;is_default_billing&gt;1&lt;/is_default_billing&gt;
    &lt;is_default_shipping&gt;1&lt;/is_default_shipping&gt;
  &lt;/data_item&gt;
&lt;/magento_api&gt;</pre>
		</div>
</div></div>
</div></div>
<p><b>response body: json</b>:</p>
<div class="panel" style="border-width: 1px;"><div class="panelcontent">
<div class="code panel" style="border-width: 1px;"><div class="codecontent panelcontent">
<div>
		<pre class="theme: default; brush: java; gutter: false">
		
[
  {
    "entity_id": "98",
    "firstname": "John",
    "middlename": null,
    "lastname": "Doe",
    "company": null,
    "city": "Philly",
    "country_id": "US",
    "region": "California",
    "postcode": "94131",
    "telephone": "888-555-1212",
    "fax": null,
    "street": [
      "123 Center St"
    ],
    "is_default_billing": 0,
    "is_default_shipping": 1
  },
  {
    "entity_id": "99",
    "firstname": "John",
    "lastname": "Doe",
    "city": "San Jose",
    "country_id": "US",
    "region": "California",
    "postcode": "94070",
    "telephone": "898-555-1212",
    "street": [
      "123 Easy St"
    ],
    "is_default_billing": 1,
    "is_default_shipping": 0
  }
]
		</pre>
		</div>
</div></div>
</div></div>
<p><b>Notes</b>: If the customer has more than two street addresses, they will be returned in the following form: first address in the first string and all other addresses in the second string separated with a semicolon (like in the example above).</p>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-POST-customers--customerid-addresses"></a>HTTP Method: POST /customers/:customer_id/addresses</h5>

<p><b>Description</b>: Allows you to create a new address for the required customer.<br/>
<b>Notes</b>: The Customer user type can create addresses only for themselves.</p>

<p>When adding a street address for the customer, it should look like the following:</p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;street&gt;
    &lt;data_item&gt;street address 1&lt;/data_item&gt;
    &lt;data_item&gt;street address 2&lt;/data_item&gt;
    &lt;data_item&gt;street address 3&lt;/data_item&gt;
&lt;/street&gt;</pre>
		</div>
</div></div>
</div></div>

<p><b>Authentication</b>: Admin, Customer<br/>
<b>Default Format</b>: XML</p>

<p><b>Parameters</b>:</p>

<table><tbody>
<tr>
<th> Name </th>
<th> Description </th>
<th> Required </th>
<th> Type </th>
<th> Example Value </th>
</tr>
<tr>
<td> firstname </td>
<td> Customer first name </td>
<td> required </td>
<td> string </td>
<td> John </td>
</tr>
<tr>
<td> lastname </td>
<td> Customer last name </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> Doe </td>
</tr>
<tr>
<td> street <br class="atl-forced-newline" /> </td>
<td> Customer street address. There can be more than one street address. </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> 2800 Watson Lane <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td> city <br class="atl-forced-newline" /> </td>
<td> Name of the city </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> Asheville <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td> country_id <br class="atl-forced-newline" /> </td>
<td> Name of the country </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> US <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td> region </td>
<td> Region name or code </td>
<td> required for countries with regions (USA, Canada, etc.) </td>
<td> string </td>
<td> Palau </td>
</tr>
<tr>
<td> postcode <br class="atl-forced-newline" /> </td>
<td> Customer ZIP/postal code </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> 28803 <br class="atl-forced-newline" /> </td>
</tr>
<tr>
<td> telephone <br class="atl-forced-newline" /> </td>
<td> Customer phone number </td>
<td> required <br class="atl-forced-newline" /> </td>
<td> string </td>
<td> 828-775-0519 <br class="atl-forced-newline" /> </td>
</tr>
</tbody></table>


<p><b>Example:</b></p>

<div class='panelMacro'><table class='infoMacro'><tr><td>POST http://magentohost/api/rest/customers/1/addresses</td></tr></table></div>

<p><b>Request Body:</b></p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;?xml version="1.0"?&gt;
&lt;magento_api&gt;
    &lt;firstname&gt;Johny&lt;/firstname&gt;
    &lt;lastname&gt;Doe&lt;/lastname&gt;
    &lt;city&gt;PA&lt;/city&gt;
    &lt;region&gt;Palau&lt;/region&gt;
    &lt;postcode&gt;19103&lt;/postcode&gt;
    &lt;country_id&gt;US&lt;/country_id&gt;
    &lt;telephone&gt;611-634-1181&lt;/telephone&gt;
    &lt;street&gt;
      &lt;data_item&gt;2354 Jody Road Philadelphia&lt;/data_item&gt;
      &lt;data_item&gt;844 Jefferson Street; 4510 Willis Avenue&lt;/data_item&gt;
    &lt;/street&gt;
&lt;/magento_api&gt;</pre>
		</div>
</div></div>
</div></div>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-PUT-customers--customerid-addresses"></a>HTTP Method: PUT /customers/:customer_id/addresses</h5>

<p><b>Update Customer Address</b>: not allowed.</p>


<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-DELETE-customers--customerid-addresses"></a>HTTP Method: DELETE /customers/:customer_id/addresses</h5>

<p><b>Description</b>: Not allowed.</p>



<h4><a name="RESTAPI-Resource-CustomerAddresses-URI--customers-addresses--addressid"></a>URI: /customers/addresses/:address_id</h4>

<p>Allows you to manage an existing customer address.</p>

<p><b>URL Structure</b>: http://magentohost/api/rest/customers/addresses/:address_id<br/>
<b>Version</b>: 1</p>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-GET-customers-addresses--addressid"></a>HTTP Method: GET /customers/addresses/:address_id</h5>

<p><b>Description</b>: Allows you to retrieve an existing customer address.<br/>
<b>Notes</b>: The list of attributes that will be returned for customer address is configured in the Magento Admin Panel. The Customer user type has access only to his/her own addresses. Also, Admin can add additional non-system customer address attributes by selecting <b>Customers</b> &gt; <b>Attributes</b> &gt; <b>Manage Customer Address Attributes</b> (available only in Magento Enterprise Edition). If these attributes are set as visible on frontend, they will be returned in the response.</p>



<p><b>Authentication</b>: Admin, Customer<br/>
<b>Default Format</b>: XML<br/>
<b>Parameters</b>:<br/>
<em>No Parameters</em></p>

<p><b>Example:</b></p>

<div class='panelMacro'><table class='infoMacro'><tr><td>GET http://magentohost/api/rest/customers/addresses/2</td></tr></table></div>

<p><b>Response Body:</b></p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;?xml version="1.0"?&gt;
&lt;magento_api&gt;
  &lt;entity_id&gt;2&lt;/entity_id&gt;
  &lt;firstname&gt;John&lt;/firstname&gt;
  &lt;lastname&gt;Doe&lt;/lastname&gt;
  &lt;city&gt;PA&lt;/city&gt;
  &lt;region&gt;Palau&lt;/region&gt;
  &lt;postcode&gt;19103&lt;/postcode&gt;
  &lt;country_id&gt;US&lt;/country_id&gt;
  &lt;telephone&gt;610-634-1181&lt;/telephone&gt;
  &lt;prefix&gt;Dr.&lt;/prefix&gt;
  &lt;middlename&gt;&lt;/middlename&gt;
  &lt;suffix&gt;Jr.&lt;/suffix&gt;
  &lt;company&gt;&lt;/company&gt;
  &lt;fax&gt;&lt;/fax&gt;
  &lt;vat_id&gt;123456789&lt;/vat_id&gt;
  &lt;street&gt;
    &lt;data_item&gt;2356 Jody Road Philadelphia&lt;/data_item&gt;
    &lt;data_item&gt;844 Jefferson Street; 4510 Willis Avenue&lt;/data_item&gt;
  &lt;/street&gt;
  &lt;is_default_billing&gt;1&lt;/is_default_billing&gt;
  &lt;is_default_shipping&gt;1&lt;/is_default_shipping&gt;
&lt;/magento_api&gt;</pre>
		</div>
</div></div>
</div></div>
<p><b>response body: json</b>:</p>
<div class="panel" style="border-width: 1px;"><div class="panelcontent">
<div class="code panel" style="border-width: 1px;"><div class="codecontent panelcontent">
<div>
		<pre class="theme: default; brush: java; gutter: false">
		
{
  "entity_id": "2",
  "firstname": "John",
  "lastname": "Doe",
  "city": "San Jose",
  "country_id": "US",
  "region": "California",
  "postcode": "94070",
  "telephone": "898-555-1212",
  "street": [
    "123 Easy St"
  ],
  "is_default_billing": 1,
  "is_default_shipping": 0
}		</pre>
		</div>
</div></div>
</div></div>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-POST-customers-addresses--addressid"></a>HTTP Method: POST /customers/addresses/:address_id</h5>

<p><b>Description</b>: Not allowed.</p>

<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-PUT-customers-addresses--addressid"></a>HTTP Method: PUT /customers/addresses/:address_id</h5>

<p><b>Description</b>: Allows you to update an existing customer address.<br/>
<b>Notes</b>: The list of attributes that will be updated for customer address is configured in the Magento Admin Panel. The Customer user type has access only to his/her own addresses.</p>

<p>If you want to add more addresses, it should look like the following:</p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;street&gt;
    &lt;data_item&gt;street address 1&lt;/data_item&gt;
    &lt;data_item&gt;street address 2&lt;/data_item&gt;
    &lt;data_item&gt;street address 3&lt;/data_item&gt;
&lt;/street&gt;</pre>
		</div>
</div></div>
</div></div>



<p><b>Authentication</b>: Admin, Customer<br/>
<b>Default Format</b>: XML</p>


<p><b>Example:</b></p>

<div class='panelMacro'><table class='infoMacro'><tr><td>PUT http://magentohost/api/rest/customers/addresses/7</td></tr></table></div>

<p><b>Request Body:</b></p>
<div class="panel" style="border-width: 1px;"><div class="panelContent">
<div class="code panel" style="border-width: 1px;"><div class="codeContent panelContent">
<div>
		<pre class="theme: Default; brush: java; gutter: false">&lt;?xml version="1.0"?&gt;
&lt;magento_api&gt;
  &lt;firstname&gt;Johny&lt;/firstname&gt;
  &lt;lastname&gt;Doe&lt;/lastname&gt;
  &lt;city&gt;PA&lt;/city&gt;
  &lt;region&gt;Palau&lt;/region&gt;
  &lt;postcode&gt;19103&lt;/postcode&gt;
  &lt;country_id&gt;US&lt;/country_id&gt;
  &lt;telephone&gt;610-634-1181&lt;/telephone&gt;
  &lt;street&gt;
    &lt;data_item&gt;2356 Jody Road Philadelphia&lt;/data_item&gt;
    &lt;data_item&gt;844 Jefferson Street&lt;/data_item&gt;
  &lt;/street&gt;
  &lt;is_default_billing&gt;1&lt;/is_default_billing&gt;
  &lt;is_default_shipping&gt;1&lt;/is_default_shipping&gt;
&lt;/magento_api&gt;</pre>
		</div>
</div></div>
</div></div>
<p><b>request body: json</b>:</p>
<div class="panel" style="border-width: 1px;"><div class="panelcontent">
<div class="code panel" style="border-width: 1px;"><div class="codecontent panelcontent">
<div>
		<pre class="theme: default; brush: java; gutter: false">
		
{
  "entity_id": "99",
  "firstname": "John",
  "lastname": "Doe",
  "city": "San Jose",
  "country_id": "US",
  "region": "California",
  "postcode": "94070",
  "telephone": "898-555-1212",
  "street": [
    "123 Easy St"
  ],
  "is_default_billing": 1,
  "is_default_shipping": 0
}		</pre>
		</div>
</div></div>
</div></div>
<h5><a name="RESTAPI-Resource-CustomerAddresses-HTTPMethod-DELETE-customers-addresses--addressid"></a>HTTP Method: DELETE /customers/addresses/:address_id</h5>

<p><b>Description</b>: Allows you to delete an existing customer address.<br/>
<b>Notes</b>: The Customer user type can delete only his/her own addresses.</p>

<p><b>Authentication</b>: Admin, Customer<br/>
<b>Default Format</b>: XML<br/>
<b>Parameters</b>:<br/>
<em>No Parameters</em></p>

<p><b>Example:</b></p>

<div class='panelMacro'><table class='infoMacro'><tr><td>DELETE http://magentohost/api/rest/customers/addresses/7</td></tr></table></div>



<h3><a name="RESTAPI-Resource-CustomerAddresses-PossibleHTTPStatusCodes"></a>Possible HTTP Status Codes</h3>


<table><tbody>
<tr>
<th> Status Code </th>
<th> Message </th>
<th> Description </th>
</tr>
<tr>
<td> 405 </td>
<td> Resource method not implemented yet. </td>
<td> The required method is not implemented or not allowed. </td>
</tr>
<tr>
<td> 404 </td>
<td> Resource not found. <br class="atl-forced-newline" /> </td>
<td> The specified resource is not found or does not exist. </td>
</tr>
<tr>
<td> 400 </td>
<td> Invalid country identifier type </td>
<td> The &lt;country_id&gt; value is passed not as a string type. </td>
</tr>
<tr>
<td> 400 </td>
<td> &lt;value name&gt; is a required value. <br class="atl-forced-newline" /> </td>
<td> The specified value is a required one. </td>
</tr>
<tr>
<td> 400 </td>
<td> Country does not exist <br class="atl-forced-newline" /> </td>
<td> The specified country does not exist. </td>
</tr>
<tr>
<td> 400 </td>
<td> Country is required </td>
<td> The &lt;country_id&gt; value is required. </td>
</tr>
<tr>
<td> 400 </td>
<td> Country is not between '2' and '3' inclusively.<br class="atl-forced-newline" /> </td>
<td> The country code is not in the range of 2 and 3 symbols inclusively. </td>
</tr>
<tr>
<td> 400 </td>
<td> Invalid State/Province type <br class="atl-forced-newline" /> </td>
<td> The &lt;region&gt; value is invalid (value is empty or passed as an array) </td>
</tr>
<tr>
<td> 400 </td>
<td> State/Province is required <br class="atl-forced-newline" /> </td>
<td> The &lt;region&gt; value is required for the specified country. </td>
</tr>
<tr>
<td> 400 </td>
<td> State/Province is invalid <br class="atl-forced-newline" /> </td>
<td> The entered value for &lt;region&gt; is invalid. It must be the region code (TX) or region name (Texas). </td>
</tr>
<tr>
<td> 400 </td>
<td> State/Province does not exist <br class="atl-forced-newline" /> </td>
<td> The specified region does not exist (only for the country with predefined regions). </td>
</tr>
<tr>
<td> 400 </td>
<td> Address is default for customer so is not allowed to be deleted <br class="atl-forced-newline" /> </td>
<td> The address cannot be deleted because it is set as a default one for billing or shipping. </td>
</tr>
</tbody></table>


		    
